home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.lzh / wind3.prf < prev    next >
Text File  |  1987-06-23  |  17KB  |  332 lines
  1. .!****************************************************************************
  2. .! 
  3. .! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
  4. .!
  5. .! ** Professional GEM ** by Tim Oren
  6. .!
  7. .! Proff File by ST enthusiasts at
  8. .! Case Western Reserve University
  9. .! Cleveland, Ohio
  10. .! uucp : decvax!cwruecmp!bammi
  11. .! csnet: bammi@case
  12. .! arpa : bammi%case@csnet-relay
  13. .! compuserve: 71515,155
  14. .!
  15. .!****************************************************************************
  16. .!
  17. .!
  18. .!****************************************************************************
  19. .!
  20. .!            Begin Part 3
  21. .!
  22. .!****************************************************************************
  23. .!
  24. .PART III THE DIALOG HANDLER
  25. .SH A MEANINGFUL DIALOG
  26. This issue of ST PRO GEM begins an exploration of ST GEM's dialog handler.  I
  27. will discuss basic system calls for presenting the dialog, and then continue
  28. with techniques for initializing and reading on/off button and "radio" button
  29. objects.  We  will also take some short side-trips into the operation
  30. of the GEM Resource Construction Set to assist you in building these dialogs.
  31. .PP
  32. There are a number of short C routines which accompany this column. These are
  33. stored as file GEMCL3.XMO in DL 5 on SIG*ATARI. Before reading this column, you
  34. should visit SIG*ATARI (go pcs-132) and download this file.
  35. .PP
  36. .SH DEFINING TERMS
  37. A dialog box is an "interactive form" in which the user may enter text and
  38. indicate selections by pointing with the mouse. Dialogs in GEM are
  39. "modal", that is, when a dialog is activated other screen functions
  40. such as menus and  window controls are suspended until the dialog is completed.
  41. .PP
  42. In most cases, the visual structure of a GEM dialog is specified within your
  43. application's resource file.  The GEM Resource Construction Set (RCS)
  44. is used to build a picture of the dialog.
  45. .PP
  46. When the RCS writes out a resource, it converts that picture into a tree of
  47. GEM drawing objects and stores this data structure within the resource.  Before
  48. your application can  display the dialog, it must load this resource file and
  49. find the  address of the tree which defines the dialog.
  50. .PP
  51. To load a resource, the AES checks its size and allocates memory for the
  52. load.  It then reads in the resource, adjusting internal pointers to
  53. reflect the load address.  Finally, the object sizes stored in the
  54. resource are converted from characters to pixels using the system font size.
  55. .PP
  56. A note for those with Macintosh experience:  Although Mac and GEM resources
  57. share a name, there are fundamental differences which can be misleading.  A Mac
  58. resource is a fork within a file; a GEM resource is a TOS file by itself.  Mac
  59. resources may be paged in and out of memory; GEM resources are monolithic.  GEM
  60. resources are internally tree structured; Mac resources are not.  Finally, Mac
  61. resources include font information, while ST GEM does this with font loading at
  62. the VDI level.
  63. .PP
  64. The resource load is done with the GEM AES call:
  65. .FB rsrc_load()
  66. ok = rsrc_load(ADDR("MYAPP.RSC"));
  67. .FE
  68. "MYAPP" should be replaced with the name of your program. Resources
  69. conventionally have the same primary name as their application, with the RSC
  70. extent name instead of PRG.  The ok flag returned by rsrc_load will be FALSE is
  71. anything went wrong during the load.
  72. .PP
  73. The most common causes of failure are the resource not being in the
  74. application's subdirectory, or lack of sufficient memory for GEM to allocate
  75. space for the resource.  If this happens, you must terminate the program
  76. immediately.
  77. .PP
  78. Once you have loaded the resource, you find the address of a dialog's object
  79. tree with:
  80. .FB rsrc_gaddr()
  81. rsrc_gaddr(R_TREE, MYDIALOG, &tree);
  82. .FE
  83. Tree is a 32-bit variable which will receive the address of the root
  84. node of the tree.
  85. .PP
  86. The mnemonic MYDIALOG should be replaced with the name you gave your dialog
  87. when defining it in the RCS.  At the same time that it writes the resource, RCS
  88. generates a corresponding .H file containing tree and object names.
  89. In order to use these mnemonics within your program, you must include
  90. the name file in your compile:  #include "MYAPP.H"
  91. .SH BUG ALERT!
  92. When using the DRI/Alcyon C compiler, .H files must be in the compiler's home
  93. directory or they will not be found.  This is especially annoying using a two
  94. floppy drive ST development system. The only way around this is to explicitly
  95. reference an alternate disk in the #include, for instance:  "B:MYAPP.H".
  96. [Ed. Note: Use the -i flag with the C pre-processor to name the include
  97. directories].
  98. .PP
  99. Now that the address of the dialog tree has been found, you are ready to
  100. display it.  The standard (and minimal) sequence for doing so is given in
  101. routine hndl_dial() in the download.  We will now walk through each
  102. step in this procedure.
  103. .PP
  104. The form_center call establishes the location of the dialog on the screen.
  105. Dialog trees generated by the RCS have an undefined origin (upper-left corner).
  106. .PP
  107. Form_center computes the upper-left location necessary to center the dialog
  108. on the screen, and inserts it into the OB_X and OB_Y fields of the ROOT object
  109. of the tree.  It also computes the screen rectangle which the dialog
  110. will occupy on screen and writes its pixel coordinates into variables
  111. xdial, ydial, wdial, and hdial.
  112. .PP
  113. There is one peculiarity of form_center which occasionally causes trouble.
  114. Normally the rectangle returned in xdial, etc., is exactly the same size as the
  115. basic dialog box.
  116. .PP
  117. However, when the OUTLINED enhancement has been specified for the box,
  118. form_center adds a three pixel margin to the rectangle returned. This
  119. causes the screen area under the outline to be correctly redrawn later
  120. (see below).  Note that OUTLINED is part of the standard dialog box in
  121. the RCS.  Other enhancements, such as SHADOWED or "outside" borders
  122. are NOT handled in this fashion, and you must compensate  for them in
  123. your code. 
  124. .PP
  125. The next part of the sequence is a form_dial call with a zero parameter.
  126. This reserves the screen for the dialog action about to occur. Note that the C
  127. binding given for form_dial in the DRI documents is in error: there are nine
  128. parameters, not five.  The first set of xywh arguments is actually used with
  129. form_dial calls 1 and 2 only, but place holders must be supplied in all cases.
  130. .PP
  131. The succeeding form_dial call (parameter one) animates a "zoom box" on the
  132. screen which moves and grows from the first screen rectangle given to
  133. the second rectangle, where the dialog will be displayed.
  134. .PP
  135. The use of this call is entirely optional.  In choosing whether to use it or
  136. not, you should consider whether the origin of the "zoom" is relevant to the
  137. operation.  For instance, a zoom from the menu bar is relatively meaningless,
  138. while a zoom from an object about to be edited in the dialog provides visual
  139. feedback to the user, showing whether the correct object was chosen.
  140. .PP
  141. If the origin is not relevant, then the zoom is just a time-waster. If  you
  142. decide to include these effects, consider a "preferences" option in  your app
  143. which will allow the experienced and jaded user to turn them off in the
  144. interests of speed.
  145. .PP
  146. The objc_draw call actually displays the dialog on the screen. Note that the
  147. address of the tree, the beginning drawing object, and the drawing depth are
  148. passed as arguments, as well as the rectangle allotted for the dialog.
  149. .PP
  150. In general, dialogs (and parts of dialogs) are  ALWAYS drawn beginning at the
  151. ROOT (object zero).  When you want to draw  only a portion of the
  152. dialog, adjust the clipping rectangle, but not the object number.
  153. This ensures that the background of the dialog is always  drawn correctly.
  154. .PP
  155. The objc_xywh() utility in the download can be used to find the clipping
  156. rectangle for any object within a dialog, though you may have to allow an extra
  157. margin is you have used shadows, outlines, or outside borders with the object.
  158. .PP
  159. Calling form_do transfers control to the AES, which animates the dialog for
  160. user interaction.  The address of the dialog tree is passed as a
  161. parameter.  The second paramter is the number of the editable object
  162. at which the text cursor will first be positioned. If you have no text
  163. fields, pass a zero.  Note that again the DRI documents are in error:
  164. pas